Padroneggiare la Navigation API: Routing e Gestione della Cronologia per Single Page Application

La Navigation API rappresenta un progresso significativo nel modo in cui gestiamo il routing e la cronologia all'interno delle Single Page Application (SPA). I metodi tradizionali si basano spesso sulla manipolazione dell'oggetto `window.location` o sull'utilizzo di librerie di terze parti. Sebbene questi approcci ci abbiano servito bene, la Navigation API offre una soluzione più snella, performante e ricca di funzionalità, fornendo agli sviluppatori un maggiore controllo sull'esperienza di navigazione dell'utente.

Cos'è la Navigation API?

La Navigation API è un'API moderna per browser progettata per semplificare e migliorare il modo in cui le SPA gestiscono la navigazione, il routing e la cronologia. Introduce un nuovo oggetto `navigation`, che fornisce metodi ed eventi che consentono agli sviluppatori di intercettare e controllare gli eventi di navigazione, aggiornare l'URL e mantenere una cronologia di navigazione coerente senza ricaricare l'intera pagina. Ciò si traduce in un'esperienza utente più veloce, fluida e reattiva.

Vantaggi dell'utilizzo della Navigation API

• Prestazioni Migliorate: Eliminando i ricaricamenti completi della pagina, la Navigation API migliora significativamente le prestazioni delle SPA. Le transizioni tra le diverse viste diventano più veloci e fluide, portando a un'esperienza utente più coinvolgente.
• Controllo Avanzato: L'API fornisce un controllo granulare sugli eventi di navigazione, consentendo agli sviluppatori di intercettare e modificare il comportamento della navigazione secondo necessità. Ciò include impedire la navigazione, reindirizzare gli utenti ed eseguire logiche personalizzate prima o dopo che la navigazione avvenga.
• Gestione della Cronologia Semplificata: La gestione dello stack della cronologia del browser è resa più facile con la Navigation API. Gli sviluppatori possono aggiungere, sostituire e scorrere programmaticamente le voci della cronologia, garantendo un'esperienza di navigazione coerente e prevedibile.
• Navigazione Dichiarativa: La Navigation API incoraggia un approccio più dichiarativo al routing, consentendo agli sviluppatori di definire regole e comportamenti di navigazione in modo chiaro e conciso. Ciò migliora la leggibilità e la manutenibilità del codice.
• Integrazione con i Framework Moderni: La Navigation API è progettata per integrarsi perfettamente con i moderni framework e librerie JavaScript, come React, Angular e Vue.js. Ciò consente agli sviluppatori di sfruttare le funzionalità dell'API all'interno dei loro flussi di lavoro di sviluppo esistenti.

Concetti e Funzionalità Fondamentali

1. L'oggetto `navigation`

Il cuore della Navigation API è l'oggetto `navigation`, accessibile tramite l'oggetto globale `window` (cioè, `window.navigation`). Questo oggetto fornisce l'accesso a varie proprietà e metodi relativi alla navigazione, tra cui:

• `currentEntry`: Restituisce un oggetto `NavigationHistoryEntry` che rappresenta la voce corrente nella cronologia di navigazione.
• `entries()`: Restituisce un array di oggetti `NavigationHistoryEntry` che rappresentano tutte le voci nella cronologia di navigazione.
• `navigate(url, { state, info, replace })`: Naviga verso un nuovo URL.
• `back()`: Torna alla voce precedente della cronologia.
• `forward()`: Va alla voce successiva della cronologia.
• `reload()`: Ricarica la pagina corrente.
• `addEventListener(event, listener)`: Aggiunge un listener di eventi per gli eventi relativi alla navigazione.

2. `NavigationHistoryEntry`

L'interfaccia `NavigationHistoryEntry` rappresenta una singola voce nella cronologia di navigazione. Fornisce informazioni sulla voce, come il suo URL, lo stato e un ID univoco.

• `url`: L'URL della voce di cronologia.
• `key`: Un identificatore univoco per la voce di cronologia.
• `id`: Un altro identificatore univoco, particolarmente utile per tracciare il ciclo di vita di un evento di navigazione.
• `sameDocument`: Un booleano che indica se la navigazione risulta in una navigazione all'interno dello stesso documento.
• `getState()`: Restituisce lo stato associato alla voce di cronologia (impostato durante la navigazione).

3. Eventi di Navigazione

La Navigation API invia diversi eventi che consentono agli sviluppatori di monitorare e controllare il comportamento della navigazione. Questi eventi includono:

• `navigate`: Inviato quando viene avviata una navigazione (ad es. cliccando un link, inviando un modulo o chiamando `navigation.navigate()`). Questo è l'evento primario per intercettare e gestire le richieste di navigazione.
• `navigatesuccess`: Inviato quando una navigazione si completa con successo.
• `navigateerror`: Inviato quando una navigazione fallisce (ad es. a causa di un errore di rete o di un'eccezione non gestita).
• `currentchange`: Inviato quando la voce corrente della cronologia cambia (ad es. navigando avanti o indietro).
• `dispose`: Inviato quando un `NavigationHistoryEntry` non è più raggiungibile, come quando viene rimosso dalla cronologia durante un'operazione di `replaceState`.

Implementare il Routing con la Navigation API: Un Esempio Pratico

Vediamo come utilizzare la Navigation API per implementare un routing di base in una semplice SPA. Consideriamo un'applicazione con tre viste: Home, About e Contact.

Per prima cosa, creiamo una funzione per gestire i cambi di rotta:

function handleRouteChange(url) {
  const contentDiv = document.getElementById('content');
  switch (url) {
    case '/':
      contentDiv.innerHTML = '
Home
Benvenuti nella pagina Home!
';
      break;
    case '/about':
      contentDiv.innerHTML = '
About
Scopri di più su di noi.
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
Contatti
Mettiti in contatto con noi.
';
      break;
    default:
      contentDiv.innerHTML = '
404 Non Trovato
Pagina non trovata.
';
  }
}

Successivamente, aggiungiamo un listener di eventi all'evento `navigate`:

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  event.preventDefault(); // Impedisce la navigazione predefinita del browser

  const promise = new Promise((resolve) => {
      handleRouteChange(url);
      resolve(); // Risolve la promise dopo aver gestito la rotta
  });

  event.transition = promise;
});

Questo codice intercetta l'evento `navigate`, estrae l'URL dall'oggetto `event.destination`, impedisce la navigazione predefinita del browser, chiama `handleRouteChange` per aggiornare il contenuto e imposta la promise `event.transition`. Impostare `event.transition` assicura che il browser attenda il completamento dell'aggiornamento del contenuto prima di aggiornare visivamente la pagina.

Infine, puoi creare dei link che attivano la navigazione:

Home | About | Contatti

E associare un listener di click a quei link:

document.addEventListener('click', (event) => {
  if (event.target.tagName === 'A' && event.target.hasAttribute('data-navigo')) {
    event.preventDefault();
    window.navigation.navigate(event.target.href);
  }
});

Questo imposta un routing di base lato client utilizzando la Navigation API. Ora, cliccando sui link si attiverà un evento di navigazione che aggiornerà il contenuto del div `content` senza un ricaricamento completo della pagina.

Aggiungere la Gestione dello Stato

La Navigation API consente anche di associare uno stato a ciascuna voce della cronologia. Questo è utile per conservare i dati tra gli eventi di navigazione. Modifichiamo l'esempio precedente per includere un oggetto di stato.

Quando si chiama `navigation.navigate()`, è possibile passare un oggetto `state`:

window.navigation.navigate('/about', { state: { pageTitle: 'Chi Siamo' } });

All'interno del listener dell'evento `navigate`, puoi accedere allo stato usando `event.destination.getState()`:

window.navigation.addEventListener('navigate', (event) => {
  const url = new URL(event.destination.url).pathname;
  const state = event.destination.getState();
  event.preventDefault();

  const promise = new Promise((resolve) => {
      handleRouteChange(url, state);
      resolve();
  });
  event.transition = promise;

});

function handleRouteChange(url, state = {}) {
  const contentDiv = document.getElementById('content');
  let title = state.pageTitle || 'La Mia App'; // Titolo predefinito

  switch (url) {
    case '/':
      contentDiv.innerHTML = '
Home
Benvenuti nella pagina Home!
';
      title = 'Home';
      break;
    case '/about':
      contentDiv.innerHTML = '
About
Scopri di più su di noi.
';
      break;
    case '/contact':
      contentDiv.innerHTML = '
Contatti
Mettiti in contatto con noi.
';
      break;
    default:
      contentDiv.innerHTML = '
404 Non Trovato
Pagina non trovata.
';
      title = '404 Non Trovato';
  }
  document.title = title;
}

In questo esempio modificato, la funzione `handleRouteChange` ora accetta un parametro `state` e lo utilizza per aggiornare il titolo del documento. Se non viene passato alcuno stato, il valore predefinito è 'La Mia App'.

Utilizzare `navigation.updateCurrentEntry()`

A volte potresti voler aggiornare lo stato della voce di cronologia corrente senza attivare una nuova navigazione. Il metodo `navigation.updateCurrentEntry()` ti permette di farlo. Ad esempio, se un utente modifica un'impostazione sulla pagina corrente, puoi aggiornare lo stato per riflettere tale modifica:

function updateUserSetting(setting, value) {
  const currentState = navigation.currentEntry.getState() || {};
  const newState = { ...currentState, [setting]: value };
  navigation.updateCurrentEntry({ state: newState });
  console.log('Impostazione aggiornata:', setting, 'a', value);
}

// Esempio di utilizzo:
updateUserSetting('theme', 'dark');

Questa funzione recupera lo stato corrente, vi unisce l'impostazione aggiornata e quindi aggiorna la voce di cronologia corrente con il nuovo stato.

Casi d'Uso Avanzati e Considerazioni

1. Gestione dell'Invio dei Moduli

La Navigation API può essere utilizzata per gestire l'invio di moduli nelle SPA, impedendo i ricaricamenti completi della pagina e fornendo un'esperienza utente più fluida. È possibile intercettare l'evento di invio del modulo e utilizzare `navigation.navigate()` per aggiornare l'URL e visualizzare i risultati senza un ricaricamento completo della pagina.

2. Operazioni Asincrone

Durante la gestione degli eventi di navigazione, potrebbe essere necessario eseguire operazioni asincrone, come il recupero di dati da un'API. La proprietà `event.transition` consente di associare una promise all'evento di navigazione, assicurando che il browser attenda il completamento dell'operazione asincrona prima di aggiornare la pagina. Vedi gli esempi sopra.

3. Ripristino dello Scorrimento

Mantenere la posizione di scorrimento durante la navigazione è fondamentale per fornire una buona esperienza utente. La Navigation API fornisce meccanismi per ripristinare la posizione di scorrimento quando si naviga indietro o avanti nella cronologia. È possibile utilizzare la proprietà `scroll` di `NavigationHistoryEntry` per memorizzare e ripristinare la posizione di scorrimento.

4. Gestione degli Errori

È essenziale gestire gli errori che possono verificarsi durante la navigazione, come errori di rete o eccezioni non gestite. L'evento `navigateerror` consente di catturare e gestire questi errori in modo elegante, impedendo che l'applicazione si blocchi o mostri un messaggio di errore all'utente.

5. Miglioramento Progressivo

Quando si creano SPA con la Navigation API, è importante considerare il miglioramento progressivo. Assicurati che la tua applicazione funzioni correttamente anche se la Navigation API non è supportata dal browser. Puoi utilizzare il rilevamento delle funzionalità per verificare la presenza dell'oggetto `navigation` e ricorrere a metodi di routing tradizionali se necessario.

Confronto con i Metodi di Routing Tradizionali

I metodi di routing tradizionali nelle SPA si basano spesso sulla manipolazione dell'oggetto `window.location` o sull'uso di librerie di terze parti come `react-router` o `vue-router`. Sebbene questi metodi siano ampiamente utilizzati e consolidati, presentano alcune limitazioni:

• Ricaricamenti Completi della Pagina: La manipolazione diretta di `window.location` può innescare ricaricamenti completi della pagina, che possono essere lenti e di disturbo per l'esperienza utente.
• Complessità: La gestione della cronologia e dello stato con i metodi tradizionali può essere complessa e soggetta a errori, specialmente in applicazioni grandi e complesse.
• Overhead Prestazionale: Le librerie di routing di terze parti possono aggiungere un notevole overhead prestazionale, specialmente se non sono ottimizzate per le esigenze specifiche della tua applicazione.

La Navigation API affronta queste limitazioni fornendo una soluzione più snella, performante e ricca di funzionalità per il routing e la gestione della cronologia. Elimina i ricaricamenti completi della pagina, semplifica la gestione della cronologia e fornisce un controllo granulare sugli eventi di navigazione.

Compatibilità dei Browser

A fine 2024, la Navigation API gode di un buon supporto sui browser moderni, inclusi Chrome, Firefox, Safari ed Edge. Tuttavia, è sempre una buona pratica controllare le ultime informazioni sulla compatibilità dei browser su risorse come Can I use prima di implementare la Navigation API nelle tue applicazioni di produzione. Se il supporto per i browser più vecchi è indispensabile, considera l'uso di un polyfill o di un meccanismo di fallback.

Conclusione

La Navigation API è un potente strumento per creare SPA moderne e performanti con funzionalità avanzate di routing e gestione della cronologia. Sfruttando le caratteristiche dell'API, gli sviluppatori possono creare esperienze utente più veloci, fluide e coinvolgenti. Sebbene la curva di apprendimento iniziale possa essere un po' più ripida rispetto all'utilizzo di metodi più semplici e datati, i vantaggi della Navigation API, specialmente in applicazioni complesse, la rendono un investimento proficuo. Abbraccia la Navigation API e sblocca il pieno potenziale delle tue SPA.

Approfondimenti

• MDN Web Docs: Navigation API
• Specifica WICG della Navigation API